/*
 * Copyright (c) 2024 Huawei Device Co., Ltd.
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 * @addtogroup OH_Scan
 * @{
 *
 * @brief 提供扫描模块C接口的定义
 *
 * @syscap SystemCapability.Print.PrintFramework
 *
 * @since 12
 * @version 1.0
 */

/**
 * @file ohscan.h
 *
 * @brief 声明用于发现和连接扫描仪、从扫描仪扫描图像、获取页面扫描进度和设置扫描图像参数等功能的API
 *
 * @library libohscan.so
 * @kit BasicServicesKit
 * @syscap SystemCapability.Print.PrintFramework
 * @since 12
 * @version 1.0
 */

#ifndef OH_SCAN_H
#define OH_SCAN_H

#include <stdint.h>
#include <stdbool.h>

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @brief 定义错误码
 *
 * @since 12
 * @version 1.0
 */
typedef enum {
    /** @error 操作成功 */
    SCAN_ERROR_NONE = 0,
    /** @error 权限验证失败 */
    SCAN_ERROR_NO_PERMISSION = 201,
    /** @error 参数无效。例如指针为空或字符串为空 */
    SCAN_ERROR_INVALID_PARAMETER = 401,
    /** @error 通用内部错误 */
    SCAN_ERROR_GENERIC_FAILURE = 24300101,
    /** @error RPC通信错误 */
    SCAN_ERROR_RPC_FAILURE = 24300102,
    /** @error 服务器错误 */
    SCAN_ERROR_SERVER_FAILURE = 24300103,
    /** @error 不支持的操作 */
    SCAN_ERROR_UNSUPPORTED = 24300104,
    /** @error 操作已取消 */
    SCAN_ERROR_CANCELED = 24300105,
    /** @error 设备繁忙，请稍后重试 */
    SCAN_ERROR_DEVICE_BUSY = 24300106,
    /** @error 数据无效（包括打开时无设备） */
    SCAN_ERROR_INVALID = 24300107,
    /** @error 文档进纸器卡纸 */
    SCAN_ERROR_JAMMED = 24300108,
    /** @error 文档进纸器缺纸 */
    SCAN_ERROR_NO_DOCS = 24300109,
    /** @error 扫描仪盖板打开 */
    SCAN_ERROR_COVER_OPEN = 24300110,
    /** @error 设备I/O错误 */
    SCAN_ERROR_IO_ERROR = 24300111,
    /** @error 内存不足 */
    SCAN_ERROR_NO_MEMORY = 24300112,
} Scan_ErrorCode;

/**
 * @brief 表示扫描仪设备信息
 *
 * @since 12
 */
typedef struct {
    /** 扫描仪ID */
    const char* scannerId;
    /** 扫描仪制造商 */
    const char* manufacturer;
    /** 扫描仪型号 */
    const char* model;
    /** 扫描仪发现模式 */
    const char* discoverMode;
    /** 扫描仪序列号 */
    const char* serialNumber;
} Scan_ScannerDevice;

/**
 * @brief 表示扫描仪扫描图片的进度
 *
 * @since 12
 */
typedef struct {
    /** 图片进度，从0到100 */
    int32_t progress;
    /** 扫描仪文件句柄 */
    int32_t fd;
    /** 指示该图像是否为最后扫描的图像 */
    bool isFinal;
} Scan_PictureScanProgress;

/**
 * @brief 表示一个扫描仪的所有参数选项
 *
 * @since 12
 */
typedef struct {
    /** 选项标题 */
    char** titles;
    /** 选项描述 */
    char** descriptions;
    /** 选项可设置的范围 */
    char** ranges;
    /** 可设置的参数选项数量 */
    int32_t optionCount;
} Scan_ScannerOptions;

/**
 * @brief 扫描仪设备发现回调，通过{@link OH_Scan_StartScannerDiscovery}注册
 * 指针指向的内存将在回调函数结束时释放
 *
 * @param devices 所有发现的扫描仪设备列表
 * @param deviceCount 发现的扫描仪数量
 * @since 12
 */
typedef void (*Scan_ScannerDiscoveryCallback)(Scan_ScannerDevice** devices, int32_t deviceCount);

/**
 * @brief 此API检查并拉起扫描服务，初始化扫描客户端，并建立与扫描服务的连接
 *
 * @permission {@code ohos.permission.PRINT}
 * @return {@link Scan_ERROR_NONE} 表示扫描服务成功启动
 *         {@link SCAN_ERROR_NO_PERMISSION} 表示无权限使用此接口
 *         {@link SCAN_ERROR_RPC_FAILURE} 表示RPC通信错误
 *         {@link SCAN_ERROR_SERVER_FAILURE} 表示扫描过程中发生错误
 * @syscap SystemCapability.Print.PrintFramework
 * @since 12
 */
int32_t OH_Scan_Init();

/**
 * @brief 此API开始发现扫描仪，注册回调函数处理发现的扫描仪设备
 *
 * @permission {@code ohos.permission.PRINT}
 * @param callback 扫描仪发现事件的{@link Scan_ScannerDiscoveryCallback}回调函数
 * @return {@link Scan_ERROR_NONE} 表示成功开始扫描仪搜索
 *         {@link SCAN_ERROR_NO_PERMISSION} 表示无权限使用此接口
 *         {@link SCAN_ERROR_RPC_FAILURE} 表示RPC通信错误
 *         {@link SCAN_ERROR_SERVER_FAILURE} 表示扫描过程中发生错误
 * @syscap SystemCapability.Print.PrintFramework
 * @since 12
 */
int32_t OH_Scan_StartScannerDiscovery(Scan_ScannerDiscoveryCallback callback);

/**
 * @brief 此API连接到扫描仪设备
 *
 * @permission {@code ohos.permission.PRINT}
 * @param scannerId 用于连接扫描仪的ID
 * @return {@link Scan_ERROR_NONE} 表示扫描仪成功连接
 *         {@link SCAN_ERROR_NO_PERMISSION} 表示无权限使用此接口
 *         {@link SCAN_ERROR_RPC_FAILURE} 表示RPC通信错误
 *         {@link SCAN_ERROR_SERVER_FAILURE} 表示扫描过程中发生错误
 *         {@link SCAN_ERROR_DEVICE_BUSY} 表示扫描仪繁忙
 *         {@link SCAN_ERROR_INVALID_PARAMETER} 表示输入参数无效
 *         {@link SCAN_ERROR_IO_ERROR} 表示与设备通信时发生错误
 *         {@link SCAN_ERROR_NO_MEMORY} 表示可用内存不足
 * @syscap SystemCapability.Print.PrintFramework
 * @since 12
 */
int32_t OH_Scan_OpenScanner(const char* scannerId);

/**
 * @brief 此API用于关闭已连接的扫描仪设备
 *
 * @permission {@code ohos.permission.PRINT}
 * @param scannerId 用于断开扫描仪连接的ID
 * @return {@link Scan_ERROR_NONE} 表示扫描仪连接成功关闭
 *         {@link SCAN_ERROR_NO_PERMISSION} 表示无权限使用此接口
 *         {@link SCAN_ERROR_RPC_FAILURE} 表示RPC通信错误
 *         {@link SCAN_ERROR_SERVER_FAILURE} 表示扫描过程中发生错误
 *         {@link SCAN_ERROR_INVALID_PARAMETER} 表示输入参数无效
 * @syscap SystemCapability.Print.PrintFramework
 * @since 12
 */
int32_t OH_Scan_CloseScanner(const char* scannerId);

/**
 * @brief 此API可用于获取扫描仪可设置的选项列表
 * 返回的结构体指针指向的内存会在{@link OH_Scan_Exit}时自动释放，
 * 每个型号在内存中只会存储一份副本
 *
 * @permission {@code ohos.permission.PRINT}
 * @param scannerId 用于获取扫描仪参数的ID
 * @param errorCode 如果执行成功，errorCode返回{@link Scan_ErrorCode#Scan_ERROR_NONE}，
 *         否则返回特定的错误码，参考{@link Print_ErrorCode}
 * @return {@link Scan_ERROR_NONE} 表示成功获取扫描仪参数选项
 *         {@link SCAN_ERROR_NO_PERMISSION} 表示无权限使用此接口
 *         {@link SCAN_ERROR_RPC_FAILURE} 表示RPC通信错误
 *         {@link SCAN_ERROR_SERVER_FAILURE} 表示扫描过程中发生错误
 *         {@link SCAN_ERROR_INVALID_PARAMETER} 表示参数无效
 * @syscap SystemCapability.Print.PrintFramework
 * @since 12
 */
Scan_ScannerOptions* OH_Scan_GetScannerParameter(const char* scannerId, int32_t* errorCode);

/**
 * @brief 此API可用于设置扫描仪的某个选项参数
 * 传入的选项和值从{@link OH_Scan_GetScannerParameter}获取
 *
 * @permission {@code ohos.permission.PRINT}
 * @param scannerId 此ID用于设置特定扫描仪的选项
 * @param option 要设置的选项编号。取值范围从0到{@link optionCount} - 1，
 * 从{@link Scan_ScannerOptions}获取
 * @param value 要设置的选项值，有效值从{@link ranges}获取，
 * 从{@link Scan_ScannerOptions}获取
 * @return {@link Scan_ERROR_NONE} 表示扫描仪参数设置成功
 *         {@link SCAN_ERROR_NO_PERMISSION} 表示无权限使用此接口
 *         {@link SCAN_ERROR_RPC_FAILURE} 表示RPC通信错误
 *         {@link SCAN_ERROR_SERVER_FAILURE} 表示扫描过程中发生错误
 *         {@link SCAN_ERROR_INVALID_PARAMETER} 表示参数无效
 * @syscap SystemCapability.Print.PrintFramework
 * @since 12
 */
int32_t OH_Scan_SetScannerParameter(const char* scannerId, const int32_t option, const char* value);

/**
 * @brief 此API允许扫描仪开始扫描
 *
 * @permission {@code ohos.permission.PRINT}
 * @param scannerId 此ID用于启动指定扫描仪的扫描任务
 * @param batchMode 是否以批处理模式启动扫描仪
 * @return {@link Scan_ERROR_NONE} 表示扫描仪成功启动扫描任务
 *         {@link SCAN_ERROR_NO_PERMISSION} 表示无权限使用此接口
 *         {@link SCAN_ERROR_RPC_FAILURE} 表示RPC通信错误
 *         {@link SCAN_ERROR_SERVER_FAILURE} 表示扫描过程中发生错误
 *         {@link SCAN_ERROR_JAMMED} 表示文档进纸器卡纸
 *         {@link SCAN_ERROR_NO_DOCS} 表示文档进纸器缺纸
 *         {@link SCAN_ERROR_COVER_OPEN} 表示扫描仪盖板打开
 *         {@link SCAN_ERROR_IO_ERROR} 表示与设备通信时发生错误
 *         {@link SCAN_ERROR_NO_MEMORY} 表示可用内存不足
 *         {@link SCAN_ERROR_INVALID_PARAMETER} 表示输入参数无效
 *         {@link SCAN_ERROR_DEVICE_BUSY} 表示设备繁忙，应稍后重试操作
 * @syscap SystemCapability.Print.PrintFramework
 * @since 12
 */
int32_t OH_Scan_StartScan(const char* scannerId, bool batchMode);

/**
 * @brief 此API允许扫描仪取消扫描
 *
 * @permission {@code ohos.permission.PRINT}
 * @param scannerId 此ID用于取消指定扫描仪的扫描任务
 * @return {@link Scan_ERROR_NONE} 表示扫描仪成功取消扫描任务
 *         {@link SCAN_ERROR_NO_PERMISSION} 表示无权限使用此接口
 *         {@link SCAN_ERROR_INVALID_PARAMETER} 表示指针为空或字符串为空
 *         {@link SCAN_ERROR_RPC_FAILURE} 表示RPC通信错误
 *         {@link SCAN_ERROR_SERVER_FAILURE} 表示扫描过程中发生错误
 * @syscap SystemCapability.Print.PrintFramework
 * @since 12
 */
int32_t OH_Scan_CancelScan(const char* scannerId);

/**
 * @brief 此API可获取扫描仪扫描图片的进度。必须传入非空值，
 * 扫描进度将写入指针指向的结构体
 *
 * @permission {@code ohos.permission.PRINT}
 * @param scannerId 用于查询扫描仪图像扫描进度的ID
 * @param prog 扫描图片的{@link Scan_PictureScanProgress}，必须为非空值
 * @return {@link Scan_ERROR_NONE} 表示扫描仪成功查询到扫描图像的进度
 *         {@link SCAN_ERROR_NO_PERMISSION} 表示无权限使用此接口
 *         {@link SCAN_ERROR_INVALID_PARAMETER} 表示指针为空或字符串为空
 *         {@link SCAN_ERROR_RPC_FAILURE} 表示RPC通信错误
 *         {@link SCAN_ERROR_SERVER_FAILURE} 表示扫描过程中发生错误
 *         {@link SCAN_ERROR_JAMMED} 表示文档进纸器卡纸
 *         {@link SCAN_ERROR_NO_DOCS} 表示文档进纸器缺纸
 *         {@link SCAN_ERROR_COVER_OPEN} 表示扫描仪盖板打开
 *         {@link SCAN_ERROR_IO_ERROR} 表示与扫描仪通信时发生错误
 *         {@link SCAN_ERROR_NO_MEMORY} 表示可用内存不足
 *         {@link SCAN_ERROR_DEVICE_BUSY} 表示设备繁忙，应稍后重试操作
 * @syscap SystemCapability.Print.PrintFramework
 * @since 12
 */
int32_t OH_Scan_GetPictureScanProgress(const char* scannerId, Scan_PictureScanProgress* prog);

/**
 * @brief 此API可用于退出扫描服务，释放扫描框架内存，
 *        并注销扫描仪发现回调
 *
 * @permission {@code ohos.permission.PRINT}
 * @return {@link Scan_ERROR_NONE} 表示扫描服务成功退出
 *         {@link SCAN_ERROR_NO_PERMISSION} 表示无权限使用此接口
 *         {@link SCAN_ERROR_RPC_FAILURE} 表示RPC通信错误
 *         {@link SCAN_ERROR_SERVER_FAILURE} 表示扫描过程中发生错误
 * @syscap SystemCapability.Print.PrintFramework
 * @since 12
 */
int32_t OH_Scan_Exit();

#ifdef __cplusplus
}
#endif

#endif  // OH_SCAN_H
/** @} */
